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Returning Values from Forms: multipart/form-data 

Abstract 
This specification defines the multipart/form-data media type, which 
can be used by a wide variety of applications and transported by a 
wide variety of protocols as a way of returning a set of values as 
the result of a user filling out a form. This document obsoletes 
RFC 2388. 
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Introduction 


In many applications, it is possible for a user to be presented with 
a form. The user will fill out the form, including information that 
is typed, generated by user input, or included from files that the 
user has selected. When the form is filled out, the data from the 


form is sent from the user to the receiving application. 


The definition of multipart/form-data is derived from one of those 
applications, originally set out in [RFC1867] and subsequently 
incorporated into HTML 3.2 [W3C.REC-htm132-19970114], where forms are 
expressed in HTML, and the form data is sent via HTTP or electronic 
mail. This representation is widely implemented in numerous web 


browsers and web servers. 
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However, multipart/form-data is also used for forms that are 
presented using representations other than HTML (spreadsheets, PDF, 
etc.) and for transport using means other than electronic mail or 
HTTP; it is used in distributed applications that do not involve 
forms at all or do not have users filling out the form. For this 
reason, this document defines a general syntax and semantics 
independent of the application for which it is used, with specific 
rules for web applications noted in context. 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in BCP 14, RFC 2119 
[RFC2119]. 


2. Percent-Encoding Option 


Within this specification, "percent-encoding" (as defined in 
[RFC3986]) is offered as a possible way of encoding characters in 
file names that are otherwise disallowed, including non-ASCII 
characters, spaces, control characters, and so forth. The encoding 
is created replacing each non-ASCII or disallowed character with a 
sequence, where each byte of the UTF-8 encoding of the character is 
represented by a percent-sign (%) followed by the (case-insensitive) 
hexadecimal of that byte. 


3. Advice for Forms and Form Processing 


The representation and interpretation of forms and the nature of form 
processing is not specified by this document. However, for forms and 
form processing that result in the generation of multipart/form-data, 
some suggestions are included. 


In a form, there is generally a sequence of fields, where each field 
is expected to be supplied with a value, e.g., by a user who fills 
out the form. Each field has a name. After a form has been filled 
out and the form’s data is "Submitted", the form processing results 
in a set of values for each field -- the "form data". 


In forms that work with multipart/form-data, field names could be 
arbitrary Unicode strings; however, restricting field names to ASCII 
will help avoid some interoperability issues (see Section 5.1). 


Within a given form, ensuring field names are unique is also helpful. 
Some fields may have default values or presupplied values in the form 
itself. Fields with presupplied values might be hidden or invisible; 
this allows using generic processing for form data from a variety of 

actual forms. 
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4. Definition of multipart/form-data 


The media type multipart/form-data follows the model of multipart 
MIME data streams as specified in Section 5.1 of [RFC2046]; changes 
are noted in this document. 


A multipart/form-data body contains a series of parts separated by a 
boundary. 


4.1. "Boundary" Parameter of multipart/form-data 


As with other multipart types, the parts are delimited with a 
boundary delimiter, constructed using CRLF, "--", and the value of 
the "boundary" parameter. The boundary is supplied as a "boundary" 
parameter to the multipart/form-data type. As noted in Section 5.1 
of [RFC2046], the boundary delimiter MUST NOT appear inside any of 
the encapsulated parts, and it is often necessary to enclose the 
"boundary" parameter values in quotes in the Content-Type header 
field. 


4.2. Content-Disposition Header Field for Each Part 


Each part MUST contain a Content-Disposition header field [RFC2183] 
where the disposition type is "form-data". The Content-—Disposition 
header field MUST also contain an additional parameter of "name"; the 
value of the "name" parameter is the original field name from the 
form (possibly encoded; see Section 5.1). For example, a part might 
contain a header field such as the following, with the body of the 
part containing the form data of the "user" field: 


Content-—Disposition: form-data; name="user" 


For form data that represents the content of a file, a name for the 
file SHOULD be supplied as well, by using a "filename" parameter of 
the Content-—Disposition header field. The file name isn’t mandatory 
for cases where the file name isn’t available or is meaningless or 
private; this might result, for example, when selection or drag-and- 
drop is used or when the form data content is streamed directly from 
a device. 


If a "filename" parameter is supplied, the requirements of 

Section 2.3 of [RFC2183] for the "receiving MUA" (i.e., the receiving 
Mail User Agent) apply to receivers of multipart/form-data as well: 
do not use the file name blindly, check and possibly change to match 
local file system conventions if applicable, and do not use directory 
path information that may be present. 
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In most multipart types, the MIME header fields in each part are 
restricted to US-ASCII; for compatibility with those systems, file 
names normally visible to users MAY be encoded using the percent- 
encoding method in Section 2, following how a "file:" URI 
[URI-SCHEME] might be encoded. 


NOTE: The encoding method described in [RFC5987], which would add a 
"filename*" parameter to the Content-—Disposition header field, MUST 
NOT be used. 


Some commonly deployed systems use multipart/form-data with file 
names directly encoded including octets outside the US-ASCII range. 
The encoding used for the file names is typically UTF-8, although 
HTML forms will use the charset associated with the form. 


4.3. Multiple Files for One Form Field 
The form data for a form field might include multiple files. 


[RFC2388] suggested that multiple files for a single form field be 
transmitted using a nested "multipart/mixed" part. This usage is 
deprecated. 


To match widely deployed implementations, multiple files MUST be sent 
by supplying each file in a separate part but all with the same 
"name" parameter. 


Receiving applications intended for wide applicability (e.g., 
multipart/form-data parsing libraries) SHOULD also support the older 
method of supplying multiple files. 


4.4. Content-Type Header Field for Each Part 


Each part MAY have an (optional) "Content-Type" header field, which 
defaults to "text/plain". If the contents of a file are to be sent, 
the file data SHOULD be labeled with an appropriate media type, if 
known, or "“application/octet-stream". 


4.5. The Charset Parameter for "text/plain" Form Data 


In the case where the form data is text, the charset parameter for 
the "text/plain" Content-Type MAY be used to indicate the character 
encoding used in that part. For example, a form with a text field in 
which a user typed "Joe owes <eu>100", where <eu> is the Euro symbol, 
might have form data returned as: 
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4. 


7. 


--AaB03x 

content-disposition: form-data; name="fieldl" 
content-type: text/plain; charset=UTF-8 
content-transfer-encoding: quoted-printable 


Joe owes =E2=82=AC100. 
—--AaB03x 


In practice, many widely deployed implementations do not supply a 
charset parameter in each part, but rather, they rely on the notion 
of a "default charset" for a multipart/form-data instance. 
Subsequent sections will explain how the default charset is 
established. 


The _charset_ Field for Default Charset 


Some form-processing applications (including HTML) have the 
convention that the value of a form entry with entry name "_charset_" 
and type "hidden" is automatically set when the form is opened; the 
value is used as the default charset of text field values (see form- 
charset in Section 5.1.2). In such cases, the value of the default 
charset for each "text/plain" part without a charset parameter is the 
supplied value. For example: 


—--AaB03x 
content-—disposition: form-data; name="_charset_" 


iso-8859-1 
—-AaB03x-— 
content-disposition: form-data; name="fieldl" 


...text encoded in iso-8859-1 
AaB03x-- 


Content-Transfer-Encoding Deprecated 


Previously, it was recommended that senders use a Content-—Transfer- 
Encoding encoding (such as "quoted-printable") for each non-ASCII 
part of a multipart/form-data body because that would allow use in 
transports that only support a "7bit" encoding. This use is 
deprecated for use in contexts that support binary data such as HTTP. 
Senders SHOULD NOT generate any parts with a Content-Transfer-— 
Encoding header field. 


Currently, no deployed implementations that send such bodies have 
been discovered. 
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4.8. Other "Content-" Header Fields 


The multipart/form-data media type does not support any MIME header 
fields in parts other than Content-Type, Content-Disposition, and (in 
limited circumstances) Content-Transfer-Encoding. Other header 
fields MUST NOT be included and MUST be ignored. 


5. Operability Considerations 
5.1. Non-ASCII Field Names and Values 


Normally, MIME header fields in multipart bodies are required to 
consist only of 7-bit data in the US-ASCII character set. While 
[RFC2388] suggested that non-ASCII field names be encoded according 
to the method in [RFC2047], this practice doesn’t seem to have been 
followed widely. 


This specification makes three sets of recommendations for three 
different states of workflow. 


5.1.1. Avoid Non-ASCII Field Names 
For broadest interoperability with existing deployed software, those 
creating forms SHOULD avoid non-ASCII field names. This should not 
be a burden because, in general, the field names are not visible to 
users. The field names in the underlying need not match what the 
user sees on the screen. 
If non-ASCII field names are unavoidable, form or application 
creators SHOULD use UTF-8 uniformly. This will minimize 
interoperability problems. 

5.1.2. Interpreting Forms and Creating multipart/form-data Data 
Some applications of this specification will supply a character 
encoding to be used for interpretation of the multipart/form-data 
body. In particular, HTML 5 [W3C.REC-htm15-20141028] uses 


o the content of a "_charset_" field, if there is one; 


o the value of an accept-charset attribute of the <form> element, if 
there is one; 


o the character encoding of the document containing the form, if it 
is US-ASCII compatible; 


o otherwise, UTF-8. 


Masinter Standards Track [Page 7] 


RFC 7578 multipart/form-data July 2015 


Call this value the form-charset. Any text, whether field name, 


field value, or ("text/plain") form data that uses characters outside 
the ASCII range MAY be represented directly encoded in the form- 
charset. 

5.1.3. Parsing and Interpreting Form Data 


While this specification provides guidance for the creation of 
multipart/form-data, parsers and interpreters should be aware of the 


variety of implementations. File systems differ as to whether and 
how they normalize Unicode names, for example. The matching of form 
elements to form-data parts may rely on a fuzzier match. In 


particular, some multipart/form-data generators might have followed 
the previous advice of [RFC2388] and used the "encoded-word" method 
of encoding non-ASCII values, as described in [RFC2047]: 


encoded-word = "=?" charset "?" encoding "?" encoded-text "?=" 


Others have been known to follow [RFC2231], to send unencoded UTF-8, 
or even to send strings encoded in the form-charset. 


For this reason, interpreting multipart/form-data (even from 
conforming generators) may require knowing the charset used in form 
encoding in cases where the _charset_ field value or a charset 
parameter of a "text/plain" Content-Type header field is not 
supplied. 


5.2. Ordered Fields and Duplicated Field Names 


Form processors given forms with a well-defined ordering SHOULD send 


back results in order. (Note that there are some forms that do not 
define a natural order.) Intermediaries MUST NOT reorder the 
results. Form parts with identical field names MUST NOT be 
coalesced. 


5.3. Interoperability with Web Applications 
Many web applications use the "application/x-www-form-urlencoded" 
method for returning data from forms. This format is quite compact, 
for example: 


name=Xaviert+Xanticoéverdict=Yesécolour=Blue&happy=sadéUt f£%F6r=Send 


However, there is no opportunity to label the enclosed data with a 
content type, apply a charset, or use other encoding mechanisms. 
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Many form-interpreting programs (primarily web browsers) now 
implement and generate multipart/form-data, but a receiving 
application might also need to support the 
"application/x-www-form-urlencoded" format. 


5.4. Correlating Form Data with the Original Form 


This specification provides no specific mechanism by which multipart/ 
form-data can be associated with the form that caused it to be 
transmitted. This separation is intentional; many different forms 
might be used for transmitting the same data. In practice, 
applications may supply a specific form processing resource (in HTML, 
the ACTION attribute in a FORM tag) for each different form. 
Alternatively, data about the form might be encoded in a "hidden 
field" (a field that is part of the form but that has a fixed value 
to be transmitted back to the form-data processor). 


6. IANA Considerations 


The media type registration of multipart/form-data has been updated 
to point to this document, using the template in Section 8. In 
addition, the registrations of the "name" parameter and the "form-— 
data" value in the "Content Disposition Values and Parameters" 
registry have been updated to both point to this document. 


7. Security Considerations 


All form-processing software should treat user supplied form-data 
with sensitivity, as it often contains confidential or personally 
identifying information. There is widespread use of form "auto-fill" 
features in web browsers; these might be used to trick users to 
unknowingly send confidential information when completing otherwise 
innocuous tasks. multipart/form-data does not supply any features 
for checking integrity, ensuring confidentiality, avoiding user 
confusion, or other security features; those concerns must be 
addressed by the form-filling and form-data-interpreting 
applications. 


Applications that receive forms and process them must be careful not 
to supply data back to the requesting form-processing site that was 
not intended to be sent. 


It is important when interpreting the filename of the Content- 


Disposition header field to not inadvertently overwrite files in the 
recipient’s file space. 
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User applications that request form information from users must be 
careful not to cause a user to send information to the requestor or a 
third party unwillingly or unwittingly. For example, a form might 
request that spam information be sent to an unintended third party or 
private information be sent to someone that the user might not 
actually intend. While this is primarily an issue for the 
representation and interpretation of forms themselves (rather than 
the data representation of the form data), the transportation of 
private information must be done in a way that does not expose it to 
unwanted prying. 


With the introduction of form-data that can reasonably send back the 
content of files from a user’s file space, the possibility arises 
that a user might be sent an automated script that fills out a form 
and then sends one of the user’s local files to another address. 
Thus, additional caution is required when executing automated 
scripting where form-data might include a user’s files. 


Files sent via multipart/form-data may contain arbitrary executable 
content, and precautions against malicious content are necessary. 


The considerations of Sections 2.3 and 5 of [RFC2183], with respect 
to the "filename" parameter of the Content-—Disposition header field, 
also apply to its usage here. 


8. Media Type Registration for multipart/form-data 


This section is the media type registration using the template from 
[RFC6838]. 


Type name: multipart 

Subtype name: form-data 

Required parameters: boundary 

Optional parameters: none 

Encoding considerations: Common use is BINARY. 
In limited use (or transports that restrict the encoding to 7bit 
or 8bit), each part is encoded separately using Content-—Transfer-— 
Encoding; see Section 4.7. 

Security considerations: See Section 7 of this document. 

Interoperability considerations: This document makes several 


recommendations for interoperability with deployed 
implementations, including Section 4.7. 
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Published specification: This document. 


July 2015 


Applications that use this media type: Numerous web browsers, 


servers, and web applications. 


Fragment identifier considerations: None; fragment identifiers are 


not defined for this type. 
Additional information: 
Additional information: 
Deprecated alias names for this type: N/A 
Magic number(s): N/A 


File extension(s): N/A 
Macintosh file type code(s): N/A 


Person & email address to contact for further information: 


this document. 
Intended usage: COMMON 
Restrictions on usage: none 
Author: Author of this document. 
Change controller: IETF 


Provisional registration: N/A 


Author of 
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Appendix A. Changes from RFC 2388 


The handling of non-ASCII field names has changed -- the method 
described in RFC 2047 is no longer recommended; instead, it is 
suggested that senders send UTF-8 field names directly and that file 
names be sent directly in the form-charset. 


The handling of multiple files submitted as the result of a single 
form field (e.g., HTML’s <input type=file multiple> element) results 
in each file having its own top-level part with the same name 
parameter; the method of using a nested "multipart/mixed" from 
[RFC2388] is no longer recommended for creators and is not required 
for receivers as there are no known implementations of senders. 


The _charset_ convention and use of an explicit "form-data" charset 
is documented; also, "boundary" is now a required parameter in 
Content-Type. 


The relationship of the ordering of fields within a form and the 
ordering of returned values within multipart/form-data was not 
defined before, nor was the handling of the case where a form has 
multiple fields with the same name. 


Various editorial changes were made; they include removing the 
obsolete discussion of alternatives from the appendix, updating the 
references, and moving the outline of form processing into the 
introduction. 


Appendix B. Alternatives 


There are numerous alternative ways in which form data can be 


encoded; many are listed in Section 5.2 of [RFC2388]. The multipart/ 
form-data encoding is verbose, especially if there are many fields 
with short values. In most use cases, this overhead isn’t 
significant. 


More problematic are the differences introduced when implementors 
opted to not follow [RFC2388] when encoding non-ASCII field names 
(perhaps because "may" should have been "MUST"). As a result, 
parsers need to be more complex for matching against the possible 
outputs of various encoding methods. 
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